home *** CD-ROM | disk | FTP | other *** search
/ MacWorld 1998 March / Macworld (1998-03) (Disk 1).dmg / Shareware World / Utilities / Text Processing / Alpha / Help / Alpha Manual < prev    next >
Encoding:
Text File  |  1997-12-13  |  83.3 KB  |  1,983 lines  |  [TEXT/ALFA]
  1.       Copyright © 1990-1996 Pete Keleher. All Rights Reserved
  2.  
  3.           (For more help, look under the system help menu!)
  4.  
  5. The Author(s) of this product are in no way liable for any direct or 
  6. indirect damage caused by the product. 
  7.  
  8. You may freely copy and distribute ALPHA, but please bear in mind that 
  9. ALPHA is Shareware.  If you decide to keep it, please register your copy 
  10. by selecting 'Register' from the 'About…' dialog.
  11.  
  12. I am collecting user-written Tcl procs at Alpha's home site.  If you have 
  13. written anything that you think may be of general interest, please send it 
  14. to me and I will make it available.
  15.  
  16. Alpha contains source from many places, but in particular I'm grateful to 
  17. Ray Johnson and Tim Endres for their working on porting TCL to the mac, and 
  18. to Tom Scavo and Tom Pollard for their Tcl code contributions.  The 
  19. following people have also provided considerable code and/or help debugging 
  20. the one or two bugs Alpha has had: Masatsugu Nagata, Karl J. Smith, Eric 
  21. Sink, David C. Black, Richard T. Austin, Henry Spencer, Vince Darley, and 
  22. Jerry Fowler.
  23.  
  24. What to do: USE THE MARKS MENU IN THIS FILE!.  This file contains "marks" 
  25. in a popup menu above the vertical scrollbar on the right, that let you 
  26. jump to different sections of this file.  Mouse-down on the M icon.
  27.  
  28. Also, Alpha supports a limited form of hypertext. Clicking on green 
  29. underlined text executes a command associated with the underlined text, 
  30. usually taking you to other documentation. Control-<period> will bring you 
  31. back.  For example, clicking here takes you to more documentation of the 
  32. hypertext capabilities.  
  33.  
  34. Alpha's hypertext links can be used to perform arbitrary tasks, including 
  35. interaction with other applications.  Once you have Internet Config 
  36. installed, the following links will all be active:
  37.     Alpha's home site:        click here (or here if no Internet Config)
  38.     Mail to the author:        click here
  39.     
  40.  
  41. Alpha is a very powerful, multi-purpose editor that allows any program- 
  42. or user-defined function to be bound to any keystroke, or placed into 
  43. user-defined menus. Every menu is defined in the macro language Tcl by 
  44. one of the startup files ("alphaBits.tcl" or one of the files sourced 
  45. from inside it). 
  46.  
  47. Alpha uses Dr.  Ousterhout's Tool Command Language (Tcl) as an extension 
  48. language.  Click here for a more complete definition of the language.  Many 
  49. of the functions bound to keystrokes, as well as many of the functions in 
  50. the user-defined menus, are written in Tcl.
  51.  
  52. Callable functions in Alpha come in two different flavors.  First, there 
  53. are the basic Tcl commands, detailed here.  Second there are "Alpha commands",
  54. commands that relate specifically to Alpha. 
  55.  
  56. The only way to get to know the editor and the language is to try different 
  57. things out.  Play around.  Choose the menu item "Misc:List Bindings" to get 
  58. a listing of all the current keystoke bindings.  Look in "procs.tcl" for 
  59. definitions of many of the routines.  Look in "menus.tcl" for 
  60. definitions of most of the menus.  See the section on "GUI Details" for 
  61. more information about the various pieces of Alpha's windows. And 
  62. finally, please feel free to send suggestions/"feature" reports/questions 
  63. to me at keleher@cs.umd.edu.  I am not able to answer US postal mail, but 
  64. if you send it to me I will at least read it.  Have fun!
  65.  
  66.  
  67.  
  68.           GUI Details
  69.  
  70. Alpha's interface has several non-standard features. First, there is a status 
  71. window across the bottom of the primary window.
  72.  
  73. Second, the horizontal scrollbar can be turned on and off via the window 
  74. menu. The default for subsequent windows is controlled via the 
  75. global variable horScrollBar (look under "Modes:Flags").
  76.  
  77. Third, above the vertical scrollbar on the right is an icon w/ curly braces 
  78. ('{}'). This is the "Funcs" menu, which lists function definitions of the 
  79. the current window if the current mode is a programming language. By 
  80. default, the functions in this menu are sorted alphanumerically. This 
  81. feature can be turned off via the global flag 'sortFuncsMenu', making the 
  82. menu appear faster on slower machines.
  83.  
  84. Below the funcs menu is the "Marks" menu, which pops up over the icon w/ 
  85. the large 'M'. The "Marks" menu lists all marks for the current window, 
  86. and allows them to be cleared or automatically created (through the Tcl 
  87. proc 'markFile' that calls mode-specific routines). Above the "Funcs" menu, 
  88. a red disk icon appears if the window is currently dirty. Clicking on this 
  89. icon saves the file.
  90.  
  91. Directly above the vertical scrollbar is a black bar that can be used to 
  92. split any window into two independent panes showing the same buffer. 
  93. Windows are split by either dragging the black bar or using the 
  94. "Windows:Split Window" menu command. Windows are unsplit the same way. 
  95. Double-clicking on the bar can also be used to toggle whether the window 
  96. is split.
  97.  
  98. Clicking on the window name brings up a popup menu that shows the 
  99. complete pathname of the file.  Command-clicking anywhere else on the 
  100. titlebar brings up the mark menu. Option-clicking on the titlebar of a 
  101. window queries the Symantec project manager for include files, if 
  102. running. 
  103.  
  104. Option-clicking and dragging text enables rectangular editing.
  105.  
  106. Control-double-clicking on any type of paren or bracket hilites from the 
  107. paren or bracket to its mate.  Without the control key held down, only the 
  108. intervening text is selected.
  109.  
  110. Command-clicking on a selection passes it to the Internet Config app. 
  111. Command-clicking on a URL, selected or not, also passes it to Internet Config.
  112.  
  113. Cmd-double-clicking in *any* mode will attempt to open a URL in the 
  114. surrounding text and send it to your web browser. If this fails, Alpha then 
  115. tries a mode-specific procedure.
  116.  
  117. Command-double clicking on a word in a C file will try to find the 
  118. definition of the word. The first option is looking up the word in the 
  119. tag file. If the word is not a tag, or no tags have been specified, Alpha 
  120. attempts to lookup the word through the THINK Reference app. If you would like 
  121. Apple's Toolbox Assistant to be used instead, edit the proc 
  122. 'cmdDoubleClick'. In Tcl mode, the verb is looked up in the SystemCode 
  123. and UserCode directories, then in ":Help:Alpha Commands", and then 
  124. finally in ":Help:Tcl Commands".
  125.  
  126. Alpha also supports drag and drop editing.
  127.  
  128. The grow region in the lower right corner is replaced by a lock icon if the 
  129. file is read-only.  Read-only status can be changed by command-clicking in 
  130. this area.
  131.  
  132. See "Status Bar" for information describing the bar running across the 
  133. bottom of the screen.
  134.  
  135. Finally, Alpha provides many different ways to move windows around the 
  136. screen, most of which are accessible via the windows menu, i.e the menu 
  137. with the window icons. The first four items of the "Windows:Arrange" menu 
  138. move windows around a virtual box on the screen, defined by vars 
  139. 'tileLeft', 'tileRight', 'tileWidth', and 'tileHeight'. The first two 
  140. affect 'numWinsToTile' windows, the others always affect two. The gap 
  141. between windows is controlled by 'tileMargin' (vertical) and 'horMargin' 
  142. (horizontal). These can be used to allow for different window types, such 
  143. as that created by Aaron or similar GUI inits. The 'Unequal Vert' and 
  144. 'Unequal Hor' items split the space between two windows, with the 
  145. proportion assigned to the first controlled by 'tileProportion'. All of 
  146. these variables can be changed via the "Config:Global:Flags:Tiling" dialog. 
  147.  
  148.  
  149.  
  150.           Searches
  151.  
  152. ALPHA has a full repertoire of searching commands.  The 'find' command 
  153. brings up a dialog allowing the search and replacement text to be 
  154. specified.  The dialog also allows 'Forward', 'Ignore Case', 'Reg Expr', 
  155. and 'Word Match' options to be set.  These options can be toggled via the 
  156. keyboard by clover-<first letter of option>.  For example, clover-w toggles 
  157. the 'Word Match' option.
  158.  
  159. The 'Mult Files' option tells Alpha to search through all files in a given 
  160. file set.  Filesets can be specified (see the section on 
  161. filesets) via the "Create Fileset…" item of the "File 
  162. Sets:Utilities" sub-menu. Filesets can be chosen via the popup fileset menu.
  163.  
  164. In addition to the current filesets, the fileset menu has an entry called 
  165. "Directory Scan". Allows you to specify a folder that will be searched. 
  166. These folders are saved at the end of the menu for future searches.
  167.  
  168. Any search can also be a "Batch" search, a list of all matches in the 
  169. fileset or current window are displayed in a new window. A particular match 
  170. can be displayed by moving the cursor to a line in the file of matches and 
  171. selecting "Goto Match" from the Utils menu (also bound to control-c 
  172. control-c).
  173.  
  174. And finally, Alpha allows a library of useful search and replace texts to 
  175. be defined as a tcl list of lists (each sublist containing a name, search 
  176. text, and replacement text). This list, the 'patternLibrary' variable 
  177. defined at the end of 'procs.tcl', is used to create a popup menu in the 
  178. find dialog allowing these patterns to be easily entered.
  179.  
  180. Once the text and options have been set, the 'Search' menu contains several 
  181. commands for repeated searching, replacing, etc. 
  182.  
  183.  
  184.           Regular Expressions
  185.  
  186. If the variable 'regExpr' is true, the search functions interpret the 
  187. search text as regular expressions, which have the following elements:
  188.  
  189.  c        literal char.
  190.  ^        beginning of line.
  191.  $        end of line.
  192.  .        any character except carriage return.
  193.  [...]    character class, can use ranges such as '0-9'.
  194.           inside classes. Matches one character of the 
  195.           enclosed choices. Ex: '[ac0-2]' matches 'a', 
  196.           'c', '0', '1', or '2'.
  197.  [^...]   negated character class, matches anything but
  198.           the enclosed characters. ']' can be included
  199.           by putting it immediately after the '^'.
  200.  \t       tab.
  201.  \r       carriage return or line break.
  202.  *        zero or more occurrences of the previous
  203.           pattern. Ex: 'ab*' matches 'a', 'ab', 'abb',
  204.           'abbb' etc.
  205.  +        one or more occurrences of the previous 
  206.           pattern. 
  207.  ?        zero or one occurrences of the previous 
  208.           pattern. Ex: 'ab?' matches 'a' or 'ab'.
  209.  a|b      matches either a or b. If enclosed in
  210.           parenthesis, the extent of the alternated
  211.           expressions is limited. Ex: (pete|bob) 
  212.           matches either 'pete' or 'bob'.
  213.  (...)    The interior elements are grouped together. 
  214.  
  215. Regular expressions constructed from the above elements can be 
  216. concatenated to create larger expressions. 
  217.  
  218. The parenthesis also define substrings of the total matched string that 
  219. can be used either later during substitution. The substring delimited by 
  220. the pair of parenthesis that includes the nth left paren is denoted \n, 
  221. where n is 1, 2, .... 9.  '\0' and '&' both refer to the matched text.
  222.  
  223. EXAMPLE: 
  224. The following regular expression will match either 'aabox' or 'bbbox':
  225.  
  226.               (aa|bb)box
  227.  
  228. In addition, \w matches an alphanumeric character (including "_") 
  229. and \W a nonalphanumeric. Word boundaries may be matched by \b, 
  230. and non-boundaries by \B. A whi- tespace character is matched by 
  231. \s, non-whitespace by \S. A numeric character is matched by \d, 
  232. non-numeric by \D. You may use \w, \s and \d within character 
  233. classes.
  234.  
  235. The class of character recognized by \w (and hence not recognized 
  236. by \W), can be augmented via the 'addAlphaChars' command.
  237.  
  238. See here for more details.  Regular expressions can be very difficult to 
  239. master, but they the following section shows how useful they can be.
  240.  
  241.  
  242.  
  243.           Searches, Incremental
  244.  
  245. Emacs users will be happy that both forward and backward incremental 
  246. searches are implemented. Incremental searches bypass the normal search 
  247. dialog and search for the current text after each keystroke. The result is 
  248. often much faster and less intrusive. Executing either while an incremental 
  249. search is in progress causes the search to proceed to the next instance of 
  250. the current text. Incremental search mode is exited when any other command 
  251. (executed through the menus or through bindings that include at least one of 
  252. the control key and the option key) is executed, or when the escape or 
  253. delete key is used. Typing control-w while incremental search is active 
  254. causes all the characters to the end of the next word boundary to be 
  255. added to the search.
  256.  
  257.  
  258.           Marks
  259.  
  260. Alpha allows the user to use "marks" to remember positions in files. Marks 
  261. "float". That is, if a mark is initially at position 312 and then five 
  262. characters are inserted at location 297, the mark's new value will be 317. 
  263. Alpha uses three different types of marks. 
  264.  
  265. The first is generically referred to as "the mark". The mark is set to the 
  266. current insertion point by the command 'setMark' (control-space by 
  267. default). The position in the file indicated by the blinking cursor is 
  268. referred to as the current insertion point. Many commands (such as "cut" 
  269. and "copy") can operate either on the currently selected (hilighted) text, 
  270. or the text between the current insertion point and "the mark". For 
  271. example, if you move the cursor to the beginning of the work "allybaba", 
  272. hit control-space (the status bar should say "Mark set"), move to the end 
  273. of the word and hit option-w (the status bar should say "Region copied"), 
  274. the effect is the same as if you had used the mouse to select the text and 
  275. then selected the "Copy" command from the "Edit" menu.
  276.  
  277. The second type of mark are the permanent marks. Permanent marks are set, 
  278. removed, and moved-to through the three corresponding menu items in the 
  279. "Search" menu. Permanent marks differ from the generic mark in that they 
  280. have names, there can be any number of them, and they are saved in the 
  281. resource fork if the file is subsequently saved.
  282.  
  283. Permanent marks can be access via the "Search:Named Marks" menu items, by 
  284. a popup menu called by mousing down on the curly braces above a vertical 
  285. scrollbar, or by command-mousing on a window's titlebar.
  286.  
  287. The third type of mark is the temporary mark. Like permanent marks, 
  288. temporary marks can be named and there can be any number of them. Unlike 
  289. permanent marks, temporary marks do not "dirty" the file, and they aren't 
  290. saved. So far, temporary marks are used exclusively to implement higher 
  291. order functions in TCL procedures. In the 5.0 release, temporary marks are 
  292. used to implement a "mark stack" and a for loop template.
  293.  
  294. At the time a file is saved, the marks for that file are stored into the 
  295. file's resource fork in an order determined by the variable 
  296. 'markSorting'. The choices are either 0 (no sorting), 1 (sort by file 
  297. position), or 2 (sort alphabetically).
  298.  
  299.  
  300.  
  301.  
  302.           Colorizing
  303.  
  304. Version 5.80 and up support automatic "colorizing" of text.  This is 
  305. controlled by the function 'regModeKeywords', which registers keywords to 
  306. colorize in a specific mode.  By default, color schemes are supplied for C, 
  307. C++, Pascal, Tcl, and TeX.  Colorizing can be turned off via the 'coloring' 
  308. flag.
  309.  
  310. You can add words to a given mode by creating a file called prefs.tcl 
  311. in the 'Alpha' subdirectory of the system preferences file, and using 
  312. regModeKeywords w/ the -a option.
  313.  
  314. Colors for keywords, strings, and comments (for applicable modes) can all 
  315. be changed via the "Config:Current Mode:Flags" menu item.
  316.  
  317. C/C++ allows function calls to be colorized.  Alpha will colorize words 
  318. immediately before left parens, assuming that they are function calls. 
  319. Use "Config:Current Mode:Flags" in C or C++ mode to turn this on.
  320.  
  321. Additionally, versions 6.02 and above allow the text color and window 
  322. background to be changed.  These are changed by redefining 'ForeGround' and 
  323. 'BackGround' in the "Config:Redefine Colors" menu.  The menu also allows all 
  324. eight of the primary colors to be redefined as well.  For instance, you can 
  325. redefine 'red', and any text that is currently red will then be the new 
  326. color you specify.  Finally, there are eight other colors 'Color_9' through 
  327. 'Color_15' that can be used though regModeKeywords etc, and values for 
  328. these can be redefined as well.
  329.  
  330.  
  331.  
  332.           C/C++
  333.  
  334. "C" and "C++" modes are selected either automatically when the file is 
  335. opened, by suffix, or via the mode popup menu on the status bar.  The 
  336. suffixes mapped to any mode can be changed via "Config:Current Mode:Flags".  
  337. To set up '*.c' and '*.h' to map to C++ rather than C, for instance, do the 
  338. following:
  339.     1) set the current mode to C
  340.     2) open up the mode dialog and remove *.c and *.h patterns from the 
  341.        'suffixes' data.
  342.     3) change the current mode to C++
  343.     4) open up the mode dialog and add *.c and *.h to 'suffixes'.
  344. That's it!
  345.  
  346. The rest of Alpha's support for C and C++ falls into four broad categories:
  347.     • "electric" editing
  348.     • colorizing
  349.     • marking
  350.     • interaction with CodeWarrior/Think
  351.  
  352. For electric editing, Alpha's default configuration is set up to perform 
  353. electric functions at left and right curly braces, semi-colons, and 
  354. carriage returns, all of which can be turned off via the 
  355. "Config:Current Mode:Flags" dialog. 
  356.  
  357. Alpha's C and C++ modes are configured by default with menus for 
  358. CodeWarrior, Symantec, Think Ref, and the Toolbox Assistant. You can prune 
  359. these to the two (or one) menu you want via the "Config:Current 
  360. Mode:Menus" menu item. Shift-click to select more than one.
  361.  
  362. Alpha automatically colorizes key-words, #defines, comments, strings, and 
  363. function calls. All colors can be changed via "Config:Current Mode:Flags", 
  364. or turned off entirely by selecting the "none" color option. New key-words 
  365. can be added by lines of the form:
  366.     regModeKeywords -a -k blue C {newword1 newword2}
  367. See the Colorizing section for more details.    
  368.  
  369. The Mark menu, accessible from the the curly brace icon above the vertical 
  370. scrollbar, allows C/C++ files to be automatically marked with a new mark 
  371. for each function in the file. You can jump to the resulting marks via the same 
  372. menu, command-clicking in the window's titlebar, or the "Text:Named 
  373. Marks:Goto" menu item. You can set up Alpha to automatically mark C/C++ 
  374. files that don't have marks on opening by selecting 'autoMark' from the 
  375. "Config:Current Mode:Flags" dialog.
  376.  
  377. Finally, Alpha is set up to closely cooperate with both Think and 
  378. Codewarrior. Follow the above links for more info.
  379.  
  380.  
  381.  
  382.  
  383.           File Detritus
  384.  
  385. The primary method of either reading or storing files with Alpha, or any 
  386. other Mac editor, is through the GetFile and PutFile dialogs. However, 
  387. Alpha's dialogs are not exactly like those of other applications. 
  388.  
  389. The GetFile dialog has two additional items: a "Read-only" checkbox and an 
  390. "All Files" checkbox.  The first allows you to open a file as read only.  
  391. Files in the read-only state can not be modified, only read.  A read-only 
  392. file is indicated by a lock icon replacing the grow zone icon.  Read-only 
  393. status can be toggled by command-clicking on the icon. The default action for 
  394. 'space' and 'backspace' when a file is read-only is to page forward 
  395. (closing at the bottom of the file) or backward.
  396.  
  397. The second checkbox, "All Files", allows Alpha to open any file rather 
  398. than just those of type 'TEXT'. The type of a file can be determined by 
  399. using the 'll' alias in the Tcl shell.
  400.  
  401.  
  402. The PutFile dialog is used to prompt the user for a new name under which to 
  403. save the contents of a window. This dialog has been enhanced by two popup 
  404. menus: "State" and "Format". "State" allows you to specify how much 
  405. information should be saved in the resource fork of files that you use. If 
  406. the state is set to "MPW", window position, current selection, tab sizes, 
  407. and font information are saved into the resource fork of your application 
  408. every time you open and close it, *even if you don't modify the file*. 
  409. Alpha still manages to coexist with build or make files because saving this 
  410. information does not change the modification date of the file. If the state 
  411. is set to "Think", neither the window position nor the current selection 
  412. are saved. If state is set to "None", no information is saved. The default 
  413. value for saved state can by changed by setting the Alpha variable 
  414. 'savedState' to "mpw", "think", or "none". Note that if a given file 
  415. already has mpw information in it when the file is open, Alpha will always 
  416. update that information when the file is closed. Note also that "marks" 
  417. are always saved in the resource fork whenever a file is saved, 
  418. regardless of the setting of the 'savedState' variable.
  419.  
  420. The "Format" menus allows the way Alpha terminates lines to be changed. 
  421. The Mac uses a carriage return to mark the end of a line, Unix uses a 
  422. linefeed, and IBM uses both (of course). Alpha can read and write any of 
  423. these formats, and can convert between them just by opening a file, 
  424. choosing "Save As", and changing the selection in this menu. Note that if 
  425. you are going to be sharing files with a Unix or IBM machine, you 
  426. probably don't want anything in your resource fork, so you'd probably 
  427. want to set 'savedState' to 'none' in your prefs.tcl file.
  428.  
  429.  
  430.           Menus
  431.  
  432. Alpha's menus are completely reconfigurable. Some of the menu items are 
  433. internal alpha commands, while others are Tcl procs defined in one of the 
  434. files of the "Tcl" subdirectory. Most of these procs are defined in 
  435. "procs.tcl". The following is an explanation of the default menus. The 
  436. explanations of items that are defined as Tcl procs are implemented by the 
  437. Tcl proc specified by "(proc <name>)", and can be found in one of the .tcl 
  438. files. All others are internal functions. 
  439.  
  440. Versions 5.98 and above use Ramon Felciano's Mercury MDEF to display 
  441. menus. In addition to allowing other modifiers to be shown in the menu, 
  442. this MDEF also allows alternates, items that change depending on the 
  443. state of the modifier keys. Alternate items are tagged below by the 
  444. modifier that must be depressed to display it.
  445.  
  446. File
  447.     New                      New file.
  448.     Open…                   Open file.
  449.     Recent…                    Menu of recently opened files. These same files
  450.                             can be opened via the 'editFile' (cmd-') proc
  451.                             from the submenu of the filesets menu.
  452.     Close                   Close file.
  453.     Close All (option)        Close all files.
  454.  
  455.     Save                       Save file.
  456.     Save All (option)        Save all files.
  457.     SaveAs…                   Prompt for name to same file under.
  458.     Revert                   Revert to last saved version, throw away undo history. 
  459.     Revert To Backup (option) Revert to last backup copy, if any.
  460.         
  461.     Shell                   Start up command-line shell that interprets Tcl 
  462.                             commands. The shell has a few csh-type features, 
  463.                             such as 'ls', 'rm', etc. commands, as well as file 
  464.                             completion with the TAB key. 
  465.  
  466.     Page Setup…               Set print options.
  467.     Print                  
  468.         Print…                Print file directly.
  469.         
  470.         Kodex C Pretty Printer        Print through Kodex app.
  471.         Enscriptor Fancy Printer    Print through Enscriptor app.
  472.         Send PS to 'Drop•PS'        Print through 'Drop•PS' app.
  473.         
  474.     Print All…    (option)    Print all files.
  475.  
  476.     Quit                       Quit Alpha.
  477.  
  478. Edit
  479.     Undo                    Undo. 
  480.     Redo (option)            Redo. 
  481.     Load                    Execute either the window or the selection as Tcl 
  482.                             source. 
  483.     Cut                        Cut selection to scrap.
  484.     Cut & Append (option)    Cut and append selection to scrap.
  485.     Copy                    Copy selection to scrap.
  486.     Copy & Append (option)    Copy and append selection to scrap.
  487.     Paste                    Paste from scrap.
  488.     Paste Pop (option)        Immediately after a paste, use a previous paste 
  489.                             instead.
  490.     Yank                    Paste last deleted text. Concatenates together 
  491.                             consecutive, adjoining deletions.
  492.  
  493.     Emacs                    Lots of Emacs key bindings.
  494.     Twiddle                    Exchange characters bracketing the selection point.
  495.     Twiddle Words (option)    Exchange words bracketing the selection point.
  496.     Select All                Select entire file.
  497.     Select Paragraph (option)    Select current paragraph.
  498.     Clear                    Delete selection.
  499.  
  500.     Shift Left                Shift selection left one tab.
  501.     Shift Left Space (option)    Shift selection left one space.
  502.     Shift Right                Shift selection right one tab.
  503.     Shift Right Space (option)    Shift selection right one space.
  504.     Balance                    Select text out to the next set of matching braces.
  505.  
  506. Text
  507.     Fill Paragraph            "Fill" paragraph that contains the insertion (proc 
  508.                             fillParagraph).
  509.     Wrap Paragraph (option)    Break lines longer than 'fillColumn' in paragraph 
  510.                             containing insertion pt (proc wrapParagraph).
  511.     Sentence Paragraph (option-shift) - Forces each sentence to start on new 
  512.                             line. 
  513.     Fill Region                "Fill" selection subject to 'leftFillColumn' and 
  514.                             'fillColumn', (proc fillRegion).
  515.     Wrap Region (option)    Break lines longer than 'fillColumn' in selection 
  516.                             (proc wrapRegion).
  517.     Sentence Region (option-shift) - Forces each sentence to start on new 
  518.                             line. 
  519.  
  520.     Sort Lines                Sort selected lines (proc sortLines).
  521.     Spellcheck Window
  522.  
  523.     Zap Invisibles            Delete all chars in file w/ ASCII code < 32, except 
  524.                             for LF, TAB and CR.
  525.     Tabs To Spaces            Convert tabs to space runs.
  526.     Spaces To Tabs            Convert space runs to tabs.
  527.  
  528.     Strings
  529.         Insert Prefix            Prepend string 'prefixString' to every line in 
  530.                                 selection (proc insertPrefix).
  531.         Remove Prefix (option)    Remove prefix string from lines in selection 
  532.                                 (proc removePrefix). 
  533.         Insert Suffix            Append string 'suffixString' to every line in 
  534.                                 selection (proc insertSuffix).
  535.         Remove Suffix (option)    Remove suffix string from lines in selection 
  536.                                 (proc removeSuffix). 
  537.         Set Prefix…                Change prefix string (proc setPrefix).
  538.         Set Suffix…                Change suffix string (proc setSuffix).
  539.     Comment Line            Comment out line, considering mode.
  540.     Uncomment Line (option)    Un-comment line, considering mode.
  541.     Comment Box                Create a comment box around selected text.
  542.     UnComment Box (option)    Remove such a comment box.
  543.     Comment Paragraph        Comment out a paragraph.
  544.     Uncomment Paragraph        Uncomment a paragraph.
  545.     Downcase Region            Downcase all chars in region.
  546.     Upcase Region            Upcase all chars in region.
  547.  
  548.     Select Last                Select text last manipulated, such as from a paste.
  549.     Named Marks
  550.         Set…
  551.         Goto…
  552.         Remove…
  553.     Unnamed Marks
  554.         Set…
  555.         Exchange Point and Mark
  556.  
  557. Search
  558.     Find…                    Present a search dialog.
  559.     Search Start (option)    Return selection point to where the last search 
  560.                             started. 
  561.     Find Again                Search forward again w/ same settings.
  562.     Find Again Backward (option)    Search backward again w/ same settings.
  563.     Find in Next File        Restart multiple-file search in next file after 
  564.                             stopping at a match.
  565.     Enter Search String        Use the current selection as the search text.
  566.     Enter Replace String (option)    Use the current selection as replace text.
  567.  
  568.     Quick Find                Incremental search forward (grep, match words off, 
  569.                             ignore case on). Type chars to define string, 
  570.                             control-w adds the current word to the search
  571.                             string, control-s/r search for the same string again.
  572.     Reverse Quick Find        Same think in reverse.
  573.     
  574.     Replace                    Replace the selection.
  575.     Replace and Find Again    Replace the selection and search again forward.
  576.     Replace All (option)    Replace all of occurances of the search string 
  577.                             in the rest of the file.
  578.     Replace in Fileset (control)    Global replace in fileset.
  579.     
  580.     Push Position            Push current pos onto a "stack".
  581.     Pop Position            Pop last pos from stack and go to it.
  582.     Goto Line                Goto specific line number.
  583.     
  584. Utils
  585.     File Utils
  586.         Insert Path Name…    Prompt for a file and insert complete pathname in 
  587.                             window.
  588.         Insert File…        Insert the text of another file.
  589.         File Remove…        Remove a file.
  590.         File Info…            Display/edit info about a file.
  591.         Word Count            Count lines, words, chars in window (proc wordCount).
  592.     Compare
  593.         Windows                Compare top two windows, sending output to a third. 
  594.                             Selecting a line in the third window and hitting 
  595.                             return (or enter) moves that line to the top of 
  596.                             the window.
  597.         Files                Same as above, but prompts for files.
  598.         Directories            As above, but works for entire directories. 
  599.     Ascii Etc
  600.         Key Code…            Wait for key press and insert keycode and modifier 
  601.                             string suitable for key binding.
  602.         Key Ascii…            Same as above, but use ascii form.
  603.         Get Ascii…            Display ascii code for char to right of insertion.
  604.         Insert Ascii…        Prompt for ascii code and insert character.
  605.         .....                Many emacs movement commands.
  606.     Kbd Macros
  607.         Start Keyboard Macro    Start creating anonymous macro.
  608.         End Keyboard Macro        Finish.
  609.         Execute Keyboard Macro    Execute.
  610.         Dump Macro                Dump to current file.
  611.  
  612.     Switch To                Bring other apps to front.
  613.     Internet Config            Start internet applications.
  614.     Send URL                Send selection as URL to proper internet app.
  615.     
  616.     Matching Lines            Find all lines that match a regular expression and 
  617.                             summarize in new window. (proc matchingLines). 
  618.     Goto Match                Jump to the original text specified by the current 
  619.                             line in a "Batch Find" or "Matching Lines" window.
  620.     Next Match                Next match.
  621.                                 
  622.     Cmd-Double Click        Look up and display definition of the selected 
  623.                             word. If in "C" or "C++" mode, use the file pointed 
  624.                             to by 'tagFile'. If in "Tcl" or "Shel" mode, look
  625.                             in "Alpha Commands", "Tcl Commands", and the "Tcl"
  626.                             subdirectory.
  627.                             
  628. Config
  629.     Current Mode            
  630.         Menus…                Change current mode's menus.
  631.         Flags…                Change options for current mode.
  632.         Edit Prefs            Edit mode-specific preferences.  Loaded 
  633.                             after mode entered for the first time.
  634.         Source Prefs        Load current mode's preferences.
  635.         Describe mode        Describe current mode's variable settings and 
  636.                             bindings.
  637.         Change…                Change the current mode.
  638.  
  639.     Global
  640.         Menus…                Set menus that will always be open.
  641.         Preferences>        Global variables.
  642.         Package menus>        Turn on/off any installed package menus
  643.             ...                
  644.         Edit prefs file        Put your own arbitrary startup code here (used to be 
  645.                             "userStartup.tcl"). Loaded after all standard Tcl 
  646.                             code. 
  647.         Describe Binding…    Wait for a keystroke, then display that keystroke's 
  648.                             binding.
  649.         List Bindings        Create a new file containing all current key bindings.
  650.         List Functions        List all functions currently defined, both
  651.                             "core" functions (those coded in C), and those
  652.                             coded in the supplied Tcl files.
  653.     Suffix Mappings…        Displays and allows editing of suffixes (really
  654.                             filename patterns) for all existing modes. 
  655.     Packages->                Turn packages on or off
  656.     Alpha downloads->        Download updated versions of Alpha or any packages
  657.                             from one of Alpha's ftp/www sites.
  658.     View Saved Settings…     Any variables or flags that you modify during
  659.                             the course of a session are saved to files in the 
  660.                             system preferences folder when Alpha quits. 
  661.                             This function shows all such saved variables.
  662.     Remove Saved Settings…    This function allows settings to be removed.
  663.     
  664.  
  665.     Set Font Tabs…            Change font and/or tabs for current file.
  666.     Redefine Colors…        See Colorizing.
  667.             
  668. Wins (an icon with three windows)
  669.     Zoom                    Zoom windows in and out.
  670.     Single Page (option)    Resize as single page.
  671.     Choose A Window            Choose window to select from list (proc 
  672.                             chooseAWindow).
  673.     Iconify                    Toggle iconification of front window.
  674.     Arrange                    Rearrange open windows.
  675.  
  676.     Split Window            Split window into two panes, or unsplit.
  677.     Toggle Scrollbar        Toggle the horizontal scrollbar on the frontmost 
  678.                             window. The scrollbar can be enabled/disabled on 
  679.                             subsequent variables by changing the value of 
  680.                             the 'horScrollBar' flag.
  681.  
  682. File Sets            
  683.         Edit File            Edit a file from one of the filesets.
  684.  
  685.         (hierarchical menus containing fileset and their files, select file to 
  686.          edit)
  687.  
  688.         Utilities
  689.             Choose                Set current fileset.
  690.             Create Fileset        Create a fileset on the fly.
  691.             Delete FileSet        Delete a fileset.
  692.  
  693.             Create Fileset From Wins    Builds a new fileset containing all
  694.                                 currently open windows.
  695.             Open Entire Fileset            Opens all files in a specified fileset.
  696.             
  697.             Create Think Fileset Create a fileset containing the source files
  698.                                 of the current Symantec project.
  699.             Create Warrior Fileset Create a fileset containing the source files
  700.                                 of the current CodeWarrior project.
  701.  
  702.             Find Tag            Find a function definition.
  703.             Create Tag File        Create a "tag" file specifying where functions
  704.                                 are defined.
  705.  
  706.             Replace In Fileset    Global search-and-replace through a fileset. Does
  707.                                 not update open windows unless told to.
  708.                                 
  709.             Rebuild Fileset Menu    Rebuilds the menu. Filesets created with 
  710.                                 globbing (all except the Symantec and 
  711.                                 CodeWarrior filesets) are re-globbed and 
  712.                                 reflect changes in the directories.
  713.                                 
  714.     
  715.           Menus, User-Defined 
  716.  
  717. All of Alpha's menus are defined in the initialization files that Alpha 
  718. loads on startup.  They can be altered or discarded at well.  Alpha's menu 
  719. commands allow the the user to build custom menus which contain names of 
  720. functions, macros, or arbitary TCL commands that just HAVE to be in the 
  721. menus, as opposed to being merely callable through the bindings.  The 
  722. syntax is dead simple.  Menus can be nested, allowing hierarchical menus to 
  723. be defined.  See the 'menus.tcl' file for examples.  The following meta 
  724. characters can be embedded in the strings:
  725.  
  726.    Meta-character     Usage
  727.    --------------     -----
  728.  
  729.     ; or Return       Separates multiple items.
  730.     ^                 Followed by an icon number, adds 
  731.                       that icon to the item.
  732.     !                 Followed by a character, marks the
  733.                       item with that character.
  734.     <                 Followed by B, I, U, O, E, or S,  
  735.                       sets the character style of the item.
  736.     /                 Followed by a character, sets up
  737.                       a keyboard equivalent.
  738.     (                 Disables the item.
  739.  
  740.  
  741. The following modifiers can be used to require other combinations of modifiers
  742. than just the command key. Control-option, for instance, is specified by 
  743. putting the string "<B<I" in the menu item. The menu symbol for shift is 
  744. an upward outline arrow, control is the outlined ^ symbol ("Files:Close All"
  745. has one), and option is the wavy line with the dot in the upper right 
  746. ("Wins:Iconify" has one). The following are characters that can follow 
  747. the '<' and what they signify.
  748.  
  749.     B        - control key required
  750.     I        - option key required
  751.     U        - shift key required (only for alpha-numerics!)
  752.     O        - command key required
  753.     S        - isDynamicItem is part of dynamic item.
  754.     E        - forces item to start new dynamic item.
  755.  
  756.  
  757. Please ignore the following:
  758.  
  759.     a    Enter            n    F10
  760.     b    Return            o    F11
  761.     c    Tab                p    F12    
  762.     d    Num Lock        q    F13
  763.     e    F1                r    F14
  764.     f    F2                s    F15
  765.     g    F3                t    Help
  766.     h    F4                u    Del
  767.     i    F5                v    Forward Del
  768.     j    F6                w    Home
  769.     k    F7                x    End
  770.     l    F8                y    Page Up
  771.     m    F9                z    Page Down
  772.     
  773.     128    Up                130    Left
  774.     129    Down            131    Right
  775.     
  776.  
  777.  
  778. The menu creation syntax is :
  779.  
  780.     menu [-s] <-n name> <-i num> [-p procName] [-m] "Tcl list of items"
  781.  
  782. Where the arguments have the followings meanings:
  783.   '-s'            Use system menu definition proc (faster).
  784.   '-i <num>'    Resource id of icon suite to use for menu title.
  785.   '-n <name>'    Name of menu.
  786.   '-m'            No menu form. If not supplied, each menu item is split into 
  787.                   words at each capitalized letter.
  788.   '-p <pname>'     Rather that having alpha call a Tcl proc named by the menu 
  789.                   item's text, this option tells Alpha to call the tcl proc 
  790.                   named by 'pname' with two arguments: the menu name, and the
  791.                   text of the menu item chosen.
  792.   '-M <mode>'    Bindings only take effect in specified mode.
  793.   
  794. Once the menus are created, they can be inserted and  deleted from the 
  795. menu bar by the syntax:
  796.  
  797.    insertMenu "name"
  798.    removeMenu "name"
  799.  
  800. as well as through macros.
  801.  
  802.  
  803. As alluded to above, Alpha attempts to make procedure names readable in the 
  804. menus by separating words at any capitalized letter. For example, 
  805. 'findFile' becomes "Find File". This function is turned off by the '-m' 
  806. option. 
  807.  
  808. Menu items can be enabled and disabled through the TCL command 
  809. 'enableMenuItem'. Menu items checkmarks can be turned on and off via 
  810. 'markMenuItem'. Menu items can be appended via 'addMenuItem' and deleted 
  811. via 'deleteMenuItem'. See the "Alpha Commands" help file for syntax. 
  812.  
  813. As explained above, the Mac ToolBox uses various keys to specify text 
  814. style and key equivalents. Sometimes you may want these characters 
  815. included in your text literally. If an ampersand ('&') is the last 
  816. character in a menu item, Alpha coerces the string so that these special 
  817. characters are not interpreted.
  818.  
  819. If an ellipsis ('…') is the last character in a menu item (except possible 
  820. for the above ampersand), it is stripped off before searching for the 
  821. function corresponding to the chosen item.
  822.  
  823.  
  824. #================================================================================
  825. # Just for the heck of it, the following is a script that I put in my 
  826. # prefs.tcl file. It creates a menu for all the .tex files in my 
  827. # thesis directory, minus the dirname and .tex extension.
  828. #
  829. set THESIS "Internal:Textures:thesis"
  830. proc thesisMenuProc {menu item} {
  831.     global THESIS
  832.     edit -r -m $THESIS:$item.tex
  833. }
  834.  
  835. set files ""
  836. foreach f [glob $THESIS:*.tex] {
  837.     lappend files [file rootname [file tail $f]]
  838. }
  839. menu -n Thesis -m -p thesisMenuProc $files
  840. unset files
  841. #================================================================================
  842.  
  843.  
  844.  
  845.           TCL
  846.  
  847. See the Tcl manual page under the 'Help' menu for a complete description of 
  848. Tcl, the Tcl shell, and its commands.  Each of the Tcl commands and 
  849. several sections have a mark defined, so you can use the "Mark" menu to 
  850. navigate through the manual page.  
  851.  
  852.  
  853.  
  854.           Key Bindings
  855.  
  856. Any TCL command can be bound to any single keystroke. One way to bind a 
  857. function is with a statement such as:
  858.   
  859.       bind 'c' <modifier string> funcName [<mode>]
  860.           
  861. where c is a character, <modifier string> is an optional string containing 
  862. one or more of:
  863.  
  864.       c   - command modifier
  865.       o   - option modifier
  866.       s   - shift modifier
  867.       z   - control modifier
  868.       e   - escape modifier      
  869.  
  870. Additionally, the modifier string can contain a capital letter specifying 
  871. that the binding is only activated if preceded by control and the lowercase 
  872. version of that letter. This feature allows multiple-key combinations ala 
  873. Emacs. The following line binds cmd-shift-f to the function 'forwardChar': 
  874.  
  875.  bind 'f' <cs> forwardChar 
  876.  
  877. The next line would bind the same function to C-x C-f, assuming that 
  878. control-x is bound to the function 'prefixChar': 
  879.  
  880.  bind 'f' <cX> forwardChar 
  881.  
  882. 'mode' is an optional parameter that specifies, when present, that the 
  883. binding is only active in a given mode, where the current mode is the 
  884. parameter to the last call of 'displayMode' (look in "procs.tcl"). Note 
  885. that given a general binding (no mode specification) and a binding specific 
  886. to the current mode, the last binding to have been created is the one found 
  887. first. 
  888.  
  889. Additionally, most keyboards have keypads and/or Function Keys. These 
  890. keys can be bound using case-insensitive numeric labels using the same 
  891. bind command as above, with the label replacing the character. For 
  892. example, to bind F1 to function 'funcName', the following would work:
  893.  
  894.     bind F1 funcName
  895.  
  896. As above, the binding can include a modifier string. The following labels 
  897. are defined for US keyboards:
  898.  
  899.   Esc F1 F2 F3 F4 F5 F6 F7 F8 F9 F10 F11 F12 F13 F14 F15 Help Home Pgup Del 
  900.   End Pgdn Left Right Up Down Clear Kpad0 Kpad1 Kpad2 Kpad3 Kpad4 Kpad5
  901.   Kpad6 Kpad7 Kpad8 Kpad9 Kpad= Kpad/ Kpad* Kpad- Kpad+ Enter Kpad.
  902.  
  903. The function 'listBindings' will list all of the bindings currently in 
  904. effect in a format suitable for re-loading.
  905.  
  906. The above labels may not be sufficient for all keyboards (attention 
  907. international users). If a hex number is used instead of a character inside 
  908. the single quotes, the binding is done to key codes instead of ascii 
  909. values. The following is a key code version of the same binding: 
  910.  
  911.       bind 0x03 <cs> forwardChar
  912.  
  913. The key code for any given key can be obtained by using the 'keyCode' 
  914. function. 
  915.  
  916. Also, there is an alternate form that allows the specification of an 
  917. ascii code directly:
  918.  
  919.     ascii 0x20 <z> setMark
  920.     
  921. Binds control-space to 'setMark'.
  922.  
  923. Note that menu item command equivalents take precedence over bindings, 
  924. and that the 'bind' command does not affect the command equivalents 
  925. displayed in the menus. Command equivalents can only be changed by using
  926. an external tool like 'ResEdit'. Also note that key code bindings take 
  927. precedence over ascii bindings. 
  928.  
  929. Finally, there are 'unbind' and 'unascii' functions, with identical 
  930. arguments to their counterparts. 
  931.  
  932. <Shf Ctl> and <Shf Opt Cmd> have been reserved for user-defined
  933. keybindings.
  934.  
  935.  
  936.           Undo + Redo
  937.  
  938. ALPHA supports unlimited undo and redo. This means that most changes can 
  939. be undone, and then redone, at will. Bear in mind that once you create new 
  940. modifications, all changes that you have undone but not redone are lost. 
  941. Another point to bear in mind is that saving a buffer to disk currently 
  942. flushes the undo buffer. 
  943.  
  944.  
  945.           Event Hooks
  946.  
  947. Alpha calls the TCL procs "openHook", "saveHook", "saveasHook", "closeHook", 
  948. "activateHook", "deactivateHook", "suspendHook", "dirtyHook", "quitHook"
  949. and "resumeHook" when the corresponding events occur. With the exception 
  950. of "saveasHook", the proc are all called with the complete pathname as the 
  951. sole argument. "saveasHook" is called with the old pathname as the first 
  952. argument and the new pathname as the second argument. Default 
  953. implementations for these commands are in the file 'modes.tcl'. These 
  954. commands can be modified to perform arbitrary commands, including saving of 
  955. files, backups, implementations of per-window variables, etc.
  956.  
  957.           Tags
  958.  
  959. ALPHA supports the use of tags to find declarations of functions; by 
  960. default this is set up only for 'C'.  When searching for a tag, ALPHA looks 
  961. for the tag file specified by the "tagFile" string variable.  ALPHA's tag 
  962. generating routines use the regular expression in the string variable 
  963. "funcExpr" to look for function declarations.  In other words, we don't 
  964. parse the text.  If you declare your functions differently, you can change 
  965. " funcExpr" to suit your own style.  Alpha currently uses the following 
  966. regular expression to find C function declarations:
  967.  
  968.               ^[^ \t#\r/@][^\r]*\([^\r]*\)$
  969.  
  970. (NOTE: the above expressions won't pick up many C++ method definitions. To 
  971. pick them up, add a question mark '?' after the last right parenthesis.) 
  972. Although complicated, this expression makes sense if you slowly wade 
  973. through it. The string that we are looking for must take up an entire 
  974. line. It must begin with a character other than '\t', '#', '\r', '/', ' ', 
  975. or '@'. There must be a set of parenthesis.   
  976.  
  977. Note that not only can you customize this to your style of 'C' 
  978. declarations, you could also use it to generate tags for other languages. 
  979. The only thing you need to bear in mind is that the tag routines use the 
  980. complete word previous to the first '(' in the selected line as the 
  981. function's name. If there is no '(' in the selected line, the last word in 
  982. the line is used. Therefore, Pascal procedures w/ or w/o parameters can be 
  983. identified.
  984.  
  985. Caveat: Apple's list manager can't handle more than 32k of text in the 
  986. entire list, so there is a practical limit of 2000 or so tags in your 
  987. project.
  988.  
  989.  
  990.           Backups
  991.  
  992. If the 'backup' variable is set in preferences files, or from the 
  993. Utils:Flags menu, Alpha backs up each file before saving new 
  994. modifications. By default, the backup file is in the same directory, and 
  995. its name is formed by suffixing a tilde to the name of the saved file. 
  996. Backups are actually performed in the 'saveHook' proc (see above), in the 
  997. file procs.tcl. The Tcl variables 'backDir' and 'backExtension' can be 
  998. used to modify this behavior.
  999.  
  1000.  
  1001.           Fill Routines
  1002.  
  1003. The "fill" and "wrap" routines reformat text to specified line lengths. 
  1004. This is useful in two case. First, word processors such as Microsoft Word 
  1005. only insert carriage returns at the end of paragraphs. Secondly, while 
  1006. typing and inserting text into pre-existing paragraphs, the line lengths 
  1007. become unequal. 
  1008.  
  1009. The "wrap" routine handles word processor documents quickly by merely 
  1010. inserting carriage returns as necessary to ensure all lines in the 
  1011. selected region are shorter than specified by the variable 'fillColumn'. 
  1012. Alpha asks the user if wrapping should be done whenever the user opens 
  1013. files that have lines longer than 'paraColumn' characters. This feature 
  1014. can be defeated by including the word 'nowrap' anywhere on the first line.
  1015.  
  1016. The TCL routines 'fillRegion' and 'fillParagraph' go further. Not only do 
  1017. they break lines, but they also coalesce lines to eliminate short lines. 
  1018. Both routines work by stripping the relevent text of white space, then 
  1019. re-inserting white space and carriage returns so that no line extends past 
  1020. 'fillColumn' characters in length and begins with 'leftFillColumn' spaces 
  1021. characters. Both routines are implemented in the file 'procs.tcl', and 
  1022. therefore different definitions of paragraphs can be accomodated by 
  1023. modifying the appropriate TCL procedures.
  1024.  
  1025.  
  1026.           Soft Text Wrapping
  1027.           
  1028. "Soft" text wrapping is re-formatting the rest of the paragraph on-the-fly 
  1029. as text is inserted and deleted.  Soft-wrapping is enabled by selecting 
  1030. "Toggle Soft Wrap" in the windows menu (or by hitting F10) for any mode that 
  1031. enables the variable 'wrapText'.  By default, 'wrapText' is enabled in the 
  1032. Text and TeX modes.  The text to be wrapped is delimited by the current 
  1033. line and the last line in the current paragraph.  Wrapping occurs after 
  1034. insertions that result in the current line becoming longer than 'wrapHigh' 
  1035. characters long (tabs counted as one character), or deletions where the 
  1036. length of the line (tabs likewise) becomes less than 'wrapLow' characters 
  1037. long.
  1038.  
  1039.  
  1040.           Word Breaking
  1041.  
  1042. Alpha allows you to redefine its internal notion of what a word is, 
  1043. through the variables 'wordBreak', and 'wordBreakPreface'. 'wordBreak' is 
  1044. set to a regular expression that defines a word to you. 'wordBreakPreface' 
  1045. should be a regular expression that matches exactly one of any characters 
  1046. that are not in your word definition. 
  1047.  
  1048. For instance, the default definition of 'wordBreak' is '[a-zA-Z0-9_]+'. 
  1049. This matches any contiguous sequence of contiguous alphanumeric 
  1050. characters, plus underscore.
  1051.  
  1052. The default value for wordBreakPreface is '[^a-zA-Z0-9_]', basically just 
  1053. the negation of any any of the characters in your 'wordBreak' definition. 
  1054.  
  1055. The need for both these variables in backward searches can be seen as 
  1056. follows. Suppose your window's text is "hey hello", and the current 
  1057. insertion is between the two 'l's. Now, searching backwards for the above 
  1058. 'wordBreak' definition will take the insertion to between the 'e' and the 
  1059. first 'l', not really where we want to say is the start of the word. By 
  1060. contrast, if we search backwards for 'wordBreak' and 'wordBreakPreface' 
  1061. concatenated together, and then move forward one character after a 
  1062. successful search, we end up right before the 'h' in 'hello', just where 
  1063. we want to be.
  1064.  
  1065.  
  1066.           File Sets
  1067.  
  1068. File Sets are lists of files that Alpha uses for multiple-file searches and 
  1069. tag searches, among other things.  Typically, a user will set up several 
  1070. different file sets, perhaps one specifying all the source files in a 
  1071. project, another specifying all the Mac include files, and another 
  1072. specifying all the UNIX include files.  When a command using file sets is 
  1073. initiated, Alpha evaluates the command "getCurrFileSet", which returns a 
  1074. list of complete pathnames to search.
  1075.  
  1076. Functions that use file sets operate on the "current" fileset, which is 
  1077. specified by the 'currFileSet' variable.  The current file set can also be 
  1078. switched by using the "File Set" hierarchical menu.  There is also a flag 
  1079. 'Auto Adjust Fileset' which will switch filesets whenever the fileset menu 
  1080. is used to open a file.
  1081.  
  1082. Selecting any item from the fileset menu opens that file.  If the flag 
  1083. 'Include Non Text Files' is set, the fileset menu may contain files Alpha 
  1084. is not designed to open; these are sent to the Finder which will open them 
  1085. using whichever application created them.  A common use of this feature is 
  1086. a hierarchical fileset containing a complete C or C++ project.  Selecting any 
  1087. project source file will open that file for editing, and selecting the 
  1088. project file/debugging symbol file/... will open that using appropriate 
  1089. tool (Symantec Project Manager or Codewarrior IDE or Debugger,…)
  1090.  
  1091. AlphaLite has no fileset utilities menu, allowing just for the creation and 
  1092. deletion of filesets.
  1093.  
  1094. Fileset Utilities
  1095. =================
  1096.  
  1097. The fileset utilities menu contains the following items:
  1098.  
  1099. NewFileset…          -- create a new fileset of one of the following 
  1100.                         six standard types (others may be added by
  1101.                         writing your own Tcl code. see "filesets.tcl"
  1102.                         and "latexFilesets.tcl" for details):
  1103.                             Codewarrior 
  1104.                             FromDirectory 
  1105.                             FromHierarchy 
  1106.                             FromOpenWindows 
  1107.                             Tex 
  1108.                             Think 
  1109.  
  1110. DeleteFileset…          -- remove a fileset, permanently if desired.
  1111. Choose                  -- a hierarchical menu from which to set the 
  1112.                         current project.
  1113. UpdateCurrentFileset -- re-build a fileset from scratch
  1114. RebuildAllFilesets      -- total menu rebuild.
  1115. ZapAndBuildFilesets  -- (hold down option) a more drastic version of the above
  1116. FindTag              -- see 'Tags' for information on this and the 
  1117.                         following item.
  1118. CreateTagFile 
  1119.  
  1120.  
  1121. HideFileset          -- if you have many filesets, some of which are only 
  1122.                         used for searching purposes, you can remove them 
  1123.                         from the menu.
  1124. BrowseFileset…          -- opens a window containing all fileset items, 
  1125.                         from which any can be opened.
  1126. CloseEntireFileset…  -- close all windows which belong to a given fileset.
  1127. FilesetToAlpha…         -- convert all text files in a fileset to Alpha's creator.
  1128. OpenEntireFileset…      -- open all files in a fileset
  1129. OpenFilesetFolder…      -- tells the Finder to open the base folder which 
  1130.                         contains a fileset.
  1131. RenameFileset…          -- change a fileset's name
  1132. ReplaceInFileset…      -- global search and replace in all files. Use this 
  1133.                         item with care!
  1134. StuffFileset…           -- If you have 'DropStuff' installed, you can archive a 
  1135.                         fileset.
  1136. WordCount              -- Count all words in a fileset 
  1137. WordCountFast          -- A quicker version which seems to have a memory leak!
  1138.  
  1139. The following flags may be set:
  1140.  
  1141. AutoAdjustFileset    -- opening a file from the menu will adjust 'currFileSet'
  1142. IncludeNonTextFiles  -- files not of type 'TEXT' may be in the menu.
  1143. IndentFilesetItems   -- visually format submenus if appropriate.
  1144. SortFilesetItems     -- force alphabetical ordering for all filesets
  1145. SortFilesetsByType   -- structure the fileset menu in a user-defined, type-
  1146.                         dependent fashion; see Personalisation.
  1147.  
  1148. Fileset Types
  1149. =============
  1150.  
  1151. 'From Directory'     -- The basic type: create a fileset of all files in a
  1152.                         given directory which match a given pattern.
  1153.                         
  1154. 'From Hierarchy'     -- Takes the above one step further and allows filesets
  1155.                         to include all files in a nested set of folders.
  1156.                         
  1157. 'From Open Windows'  -- Make a fileset containing all currently open windows.
  1158.  
  1159. 'Codewarrior'         -- Query the Codewarrior IDE for a list of all files in
  1160.                         the current project.
  1161.                         
  1162. 'Think'                 -- Query the Symantec Project Manager for a list of all
  1163.                         files in the current project.
  1164.  
  1165. 'Tex'                 -- Make a fileset of all parts of a multi-part TeX/LaTeX
  1166.                         document.  Alpha's LaTeX mode understands these and
  1167.                         will automatically send your TeX application the base
  1168.                         .tex/.ltx file when you select 'Typeset' on any 
  1169.                         component part.
  1170.                         
  1171. The following items will be added to the utilities menu if you use 
  1172. TeX filesets:
  1173.  
  1174. ExtractEpsBoxSizes   -- search all document parts for included eps graphics,  
  1175.                         extract bounding box information from the .eps files 
  1176.                         and insert it explicitly into the document (can lead 
  1177.                         to much quicker typesetting).
  1178. DeleteEpsBoxSizes    -- remove all the above bounding box information
  1179. HierarchicalBibFiles -- bibliography files may \input others, so they should
  1180.                         be searched (the default is not to do this, because
  1181.                         .bib files may be enormous).
  1182.  
  1183. Personalisation
  1184. ===============
  1185.  
  1186. As well as adjusting the aforementioned flags, the fileset menu allows 
  1187. complete user control of the structure of the menu in the following way: 
  1188. Set the 'Sort Filesets By Type' flag, and set the variable 
  1189. "filesetSortOrder" as follows:
  1190.  
  1191.    The structure of    this variable dictates how the fileset
  1192.    menu    is structured:
  1193.        
  1194.        '{pattern p}' 
  1195.            lists all filesets which    match 'p'
  1196.        '-' 
  1197.            adds    a separator    line
  1198.        '{list of types}' 
  1199.            lists all filesets of those types.
  1200.        '{submenu name sub-order-list}' 
  1201.            adds    a submenu with name    'name' and recursively
  1202.            adds    filesets to    that submenu as    given by the 
  1203.            sub-order.
  1204.            
  1205.    Leading,    trailing and double    separators are automatically
  1206.    removed.
  1207.  
  1208. For example, the default value of this variable (more as an example than 
  1209. anything else) is:
  1210.  
  1211. set filesetSortOrder { {pattern System} {pattern User} {pattern Preferences} \
  1212.                         - {tex} - {pattern *.cc} \
  1213.                         {submenu Headers {pattern *.h}} \
  1214.                         - {fromDirectory think codewarrior \
  1215.                         fromOpenWindows fromHierarchy} * } 
  1216.  
  1217. You can and should over-ride this in your "prefs.tcl" file (copy and paste 
  1218. from here, then make your changes).
  1219.  
  1220.  
  1221.           Macros, Keyboard
  1222.  
  1223. Defining and Using Keyboard Macros ALPHA supports keyboard macros which 
  1224. record a sequence of keystrokes to be played back later w/ the function 
  1225. 'executeKeyboardMacro' (this function is also in the 'Utilities' menu) or 
  1226. written into a buffer by selecting 'Dump Macro' from the 'Utilities' menu. 
  1227. The dump function prompts you for a macro name, which must consist only of 
  1228. letters of the alphabet, digits, and '_'. 
  1229.  
  1230. These macro declarations can then be edited, loaded, and bound to 
  1231. keystrokes.  Loading a macro or a binding is accomplished by hiliting the 
  1232. text and selecting the "Load" item of the 'Edit' menu.  If no text is 
  1233. hilited, the entire window is loaded by the same command.  Macros can be 
  1234. bound to keys in exactly the same manner as functions (see above).
  1235.  
  1236.  
  1237.           THINK and Alpha
  1238.  
  1239. Yes! Finally Think has support for external editors (7.0 or better).  To 
  1240. make this work, put an alias of Alpha in the "Tools" subdirectory of the 
  1241. directory the project manager is in, and name the alias "Editor".  
  1242. Secondly, check the "Use External Editor" button in the project manager's 
  1243. option dialog.  You do not have to check the "Always Check File Dates" 
  1244. button.
  1245.  
  1246. Any open window events will now be vectored to Alpha, and from within 
  1247. Alpha you can initiate compiles, disassembles, makes, etc. Errors are 
  1248. reported back to Alpha.
  1249.  
  1250. Look in :Tcl:Menus:"think.tcl" for the code controlling much of the 
  1251. interactions between THINK and Alpha.  If you improve anything, please send 
  1252. it back to me.
  1253.  
  1254. If a window contains a file that is part of the a project that is 
  1255. currently open in the Think Project Manager, selecting "Open Header" from 
  1256. the Think menu will put up a list of include files. The same files can be 
  1257. accessed by option-clicking on the window's title-bar.
  1258.  
  1259. A fileset consisting of the source to a think project can be created 
  1260. through the "File:File Sets" menu.
  1261.  
  1262.  
  1263.           Rectangular Editing
  1264.  
  1265. If the option key is pressed while the mouse is dragged,  a rectangular 
  1266. section of text is selected instead of the normal selection. This 
  1267. rectangular selection may extend over multiple lines, but contains only 
  1268. text between the column of the drag start and the column of the drag end. 
  1269. The drag cannot end on a column or row less than the start. This selection 
  1270. can be extended by option-shift-mouse, but not dragged further.
  1271.  
  1272. The rectangular selection can be deleted, copied, and pasted. This is very 
  1273. useful for tables and arrays, such as in LaTeX. Usually, the operation 
  1274. will be intuitive. However, if you use proportional fonts the selection 
  1275. may appear ragged. If some of the line contain tabs, the result may not be 
  1276. want you want. Converting tabs to spaces in the desired region before 
  1277. attempting rectangular selection usually fixes the problems. 
  1278.  
  1279. The most natural semantics of rectangular selection aren't obvious. I 
  1280. chose to implement it in a similar fashion to that of Microsoft Word. 
  1281. Preditor does it in another way, and has many bugs (and it's  commercial, 
  1282. hah!).
  1283.  
  1284.  
  1285.  
  1286.           LaTeX
  1287.  
  1288. See the "LaTeX Help" file under the help menu.
  1289.  
  1290.  
  1291.  
  1292.  
  1293.           System Software 7.0
  1294.  
  1295. Alpha is 32-bit clean and high-level event aware. 
  1296.  
  1297. Under 7.0, Alpha uses temporary memory to accommodate large files. This 
  1298. allows you to open multi-megabyte files even when Alpha's partition is set 
  1299. only at 512k, if the system has that much memory available. Note that 
  1300. using temporary memory makes that much memory unavailable to other 
  1301. applications. Contrary to all admonishments, Alpha does not unlock 
  1302. temporary memory across WaitNextEvent calls and may eventually use all the 
  1303. memory in your system. You can turn this feature off through 'tempMem'.
  1304.  
  1305. Note, however, that the clipboard is allocated by the system in Alpha's 
  1306. heap, and therefore cannot take advantage of temporary memory.
  1307.  
  1308.  
  1309.  
  1310.  
  1311.           Apple Events
  1312.  
  1313. See the Help file on AppleEvents.
  1314.  
  1315.  
  1316.           MPW
  1317.  
  1318. Alpha's 'dosc' capability (see the function "dosc") can be used to send 
  1319. events to MPW's ToolServer. Using about ten lines of C code and the ~40 
  1320. lines of Tcl code in 'mpw.tcl', I created a pseudo mpw shell (look under 
  1321. the "Misc" menu). This shell uses Alpha's 'dosc' function to package each 
  1322. shell command up into an Apple Event and send it to the ToolServer, which 
  1323. then evaluates the command and returns the result to be displayed in the 
  1324. shell. I'm rather new to Apple Events and the ToolServer, so there are 
  1325. probably a few rough edges. 
  1326.  
  1327. If anyone has extensive docs for ToolServer I'd appreciate looking at them. 
  1328. I only have the application because I am a beta tester for another product 
  1329. that supports ToolServer. I was given the application for the beta testing, 
  1330. but not any docs. And of course, I can *not* give away copies of 
  1331. ToolServer because it is a licensed Apple product.
  1332.  
  1333. Finally, Tom Moertel (thor@vivaldi.psu.edu) has written and provided a set 
  1334. of tools that make life easier while writing code in Alpha for the MPW 
  1335. environment. The tools make extensive use of Apple Events, so you must be 
  1336. using MPW 3.3a or greater. (Earlier versions cannot receive commands via 
  1337. Apple Events.) 
  1338.  
  1339.   With the MPW-Alpha package you can:
  1340.   
  1341.     o  Send TCL commands to Alpha from MPW
  1342.     o  Use MPW 411 from Alpha for instant access to programming help
  1343.     o  Automagically locate source code errors from your last MPW compile
  1344.     o  Use the MPW CDent tool to reformat (grind) C/C++ source code
  1345.        from within Alpha
  1346.  
  1347. This package is available via anonymous ftp from cs.umd.edu.
  1348.  
  1349.  
  1350.           File Formats
  1351.  
  1352. Alpha reads and writes files stored in three (or maybe four) different 
  1353. formats. The three main formats are mac (lines end with a carriage 
  1354. return), unix (lines end with linefeed), and IBM pc (lines end with both 
  1355. carriage return and linefeed. Typical, isn't it?).
  1356.  
  1357. Alpha will transparently read and write all three of these formats. You 
  1358. don't have to do anything special to use different formats, but the 
  1359. 'SaveAs...' dialog allows you to specify the format that a file is written 
  1360. in through the 'Format' button.
  1361.  
  1362. The fourth file format is just a modification of the ordinary mac format. 
  1363. Word processors such as Microsoft Word and MacWrite only put carriage 
  1364. returns at the end of paragraphs, so that they can wrap  the paragraphs on 
  1365. the fly. This is what is referred to as 'paragraph format' in the rest of 
  1366. the help text. Alpha does not transparently convert to and from this 
  1367. format because there are valid reasons why someone might want to edit a 
  1368. paragraph formatted file while not in paragraph mode. 
  1369.  
  1370. Therefore, when Alpha detects reads a paragraph-mode file, it asks the 
  1371. user whether or not to remap it. Files can be mapped back to paragraph 
  1372. mode by setting 'fillColumn' to a very large number and executing 
  1373. 'fillRegion' on the text.
  1374.  
  1375.           Printing
  1376.  
  1377. Version 6.0 and above have many printing options available. Printing is 
  1378. accomplished via a submenu under the File menu. The menus allows printing 
  1379. either via Alpha or several other applications.
  1380.  
  1381. If printing through alpha, the variables 'printHeader', 'printHeaderTime', 
  1382. and 'printHeaderFullPath' control whether and what type of header is 
  1383. printed at the top of each page. These flags are actually used in the procs 
  1384. 'printLeftHeader' and 'printRightHeader' (in procs.tcl) to create the 
  1385. string that appears on the left side of the top of the page. 'leftMargin', 
  1386. 'topMargin', and 'bottomMargin' control margins on the printed page.
  1387.  
  1388. 'printerFont' and 'printerFontSize' allows the size and type of the 
  1389. printed font to be specified.
  1390.  
  1391. The external apps that Alpha is currently configured to use are 
  1392. "Enscriptor", an app that allows multi-column and other options, "Kodex", 
  1393. a "C" pretty printer, and "Drop•PS", which prints postscript files. All 
  1394. options operate on the frontmost window. These applications are not 
  1395. supplied w/ Alpha, but can be downloaded from any comprehensive mac site. 
  1396. They can also be downloaded from Alpha's home site. "Enscriptor" and 
  1397. "Kodex" are shareware apps written by John Cho. "Drop•PS" is a freeware 
  1398. app written by some evil commercial text editor guru :-).
  1399.  
  1400.  
  1401.           Random Tips
  1402.  
  1403. - When a window is "dirty" (has unsaved changes), a
  1404.   red disk icon appears just below the titlebar in the
  1405.   upper right corner of the window, and a diamond 
  1406.   appears next to the corresponding item in the Windows
  1407.   menu. 
  1408.  
  1409. - All dialogs that have editable text can use the Cut, 
  1410.   Copy, and Paste menu command equivalents.
  1411.  
  1412. - In all dialogs, non-editable controls can be selected 
  1413.   by typing Command-<first char of control>. If there 
  1414.   are no editable controls in the dialog, simply typing 
  1415.   the first letter of the desired control suffices. PgUp,
  1416.   PgDown, Home, and End keys now work for most list dialogs.
  1417.  
  1418. - Set the flag 'undoOn' to 0 in order to speed up long 
  1419.   replace-all and macro modifications.
  1420.  
  1421. - After a piece of text has been yank'd or paste'd, the 
  1422.   'mark' is set to the beginning of the new text and the
  1423.   selection is at the end. 'markHilite' will now hilite 
  1424.   the entire insertion. This is especially useful when
  1425.   moving code. Cut the code, insert at a new position,
  1426.   select the inserted text by selecting "Edit:Hilite", and 
  1427.   then use "Edit:Shift Left" and "Edit: Shift Right" to move
  1428.   the text to the proper indentation.
  1429.  
  1430. - Most help files have marks in them, which let you quickly
  1431.   navigate to places of interest. You can access these marks
  1432.   by command-clicking on the title-bar or on the "{}" icon
  1433.   above the vertical scrollbar.
  1434.  
  1435.  
  1436.  
  1437.           Variables 
  1438.  
  1439. There are two different kinds of variables in the Alpha world: global 
  1440. vars and mode vars. Mode vars can have different values in each mode, and 
  1441. are modified by the "Mode Vars" popup menu over the checkmark just 
  1442. above vertical scrollbar. Changing one of these variables changes the 
  1443. variable's value for all windows of the current mode.
  1444.  
  1445. Global variables are accessed via the "Config:Flags" and "Config:Vars" menus. 
  1446. Changing one of these variables affects all windows.
  1447.  
  1448. Alpha records which variables are modified in the course of a session and 
  1449. prompts the user to save them prior to quitting.
  1450.  
  1451.  
  1452. Mode Vars
  1453.  
  1454. autoMark       • Automatically mark windows on open if they don't have marks.
  1455. doubleSpaces   • If true, fill routines end all sentences w/ double spaces.
  1456. elecLBrace     • Electric 'C' left brace on.
  1457. elecRBrace     • Electric 'C' right brace on.
  1458. electricSemi   • Electric 'C' semicolon on.
  1459. fillColumn     • Number of columns use as limit for
  1460.                  "fill" routines. See 'leftFillColumn'
  1461. funcExpr       • Set to the regular expression that 
  1462.                  ALPHA uses to find function 
  1463.                  declarations.
  1464. leftFillColumn • Number of blanks left at beginning of 
  1465.                  lines by 'fill' routines. 
  1466. parseExpr      • Set to the regular expression used by parseFuncsAlpha to 
  1467.                  extract the name of a function from the text returned by a
  1468.                  search for funcExpr.
  1469. wordBreak       • Regular expression used to defines words for all internal 
  1470.                  operations. 
  1471. wordBreakPreface • Prepended to 'wordBreak' when looking backwards for a 
  1472.                  word. See the "Word Break" section of this file for more 
  1473.                  information.
  1474. wordWrap       • if true, lines exceeding 'fillColumn'
  1475.                  in length are automatically wrapped
  1476.                  during normal text insertion (typing)
  1477. wrapBreak       • Reg expr used for automatic word wrapping.
  1478. wrapBreakPreface • Reg expr used for automatic word wrapping.
  1479.  
  1480. Global Vars
  1481. autoHScroll       • Automatically scroll horizontal scrollbar
  1482.                  to follow insertion.
  1483. autoSave       • If TRUE, buffers (except untitled buffers) are automatically
  1484.                  saved every 'changesLim' changes.
  1485. backDir           • Directory in which to store backup files.
  1486. backExtension  • Suffix to append to backup files.
  1487. backup         • if TRUE, the default Tcl proc 'saveHook' makes a backup 
  1488.                  of a file before the data is written. The default backup
  1489.                  scheme has extension "~".
  1490. blinkCursor    • Cursor blinks
  1491. blockCursor    • if true, Alpha uses a block cursor instead of a vertical 
  1492.                  line. 
  1493. bottomMargin   • Bottom print margin.
  1494. bwWindows      • if true, Alpha will use 1-bit windows
  1495.                  even if color is available. This speeds
  1496.                  refresh quite a bit on slow color 
  1497.                  machines such as the IIsi.
  1498. changesLim     • number of changes to a window before 
  1499.                  garbage collection or autosave is done.
  1500. coloring       • enable keyword coloring.
  1501. def{Height,Left,Top,Width} • If 'fullScreen' set, default size
  1502.                  of windows.
  1503. defaultFont    • font to use on new windows and files 
  1504.                  which don't have associated font 
  1505.                  specification resources.
  1506. diffFlags       • Command line args to pass to GNU diff.
  1507. dragAndDrop       • Enable drag and drop.
  1508. fontSize       • Default size of fonts used to display 
  1509.                  files.
  1510. forceMainScreen• If true, forces windows to main screen. Useful if you 
  1511.                  have a small screen and windows habitually are too large.
  1512. fullNames      • Windows display pathnames instead of 
  1513.                  mere file names.
  1514. fullScreen     • If on, all windows are start in the 
  1515.                  same place, and have the dimension 
  1516.                  specified by 'defHeight' and 
  1517.                  'defWidth'.
  1518. horScrollBar   • If set, use horizontal scrollbar.
  1519. iconifyOnSwitch• Iconify all windows when suspending.
  1520. indentOnCR     • Auto-indent on carriage return.
  1521. infoWindowsDirty• Dirty/Clean state of description windows.
  1522. intelCutPaste  • Enable intelligent cut and paste.
  1523. lockStatus       • Disable status window dragging.
  1524. maskCapsLock   • Mask caps lock bit on key depresses.
  1525. moveInsertion  • if true, 'pageBack' and 'pageForward'
  1526.                  move the insertion point
  1527. numWinsToTile  • specifies the number of windows tile
  1528.                  commands should affect.
  1529. paraColumn     • Alpha automatically wraps files
  1530.                 that contains lines longer than this. 
  1531. posActivate    • If true, then merely moving the mouse
  1532.                  over a window activates. For those
  1533.                  X11-twm lovers.
  1534. powerThumb       • If true, vertical scrollbars have power thumbs.
  1535. printerFont       • Font to print documents.
  1536. printerFontSize• Size to print documents.
  1537. projectorAware • Respect projector resources.
  1538. savedState       • set to either "mpw", "think", or "none" depending on how 
  1539.                  much information you wish Alpha to save in the resource 
  1540.                  fork of the files you edit. See the "Files" section of 
  1541.                  this file for more information.
  1542. showInvisibles • Show spaces, tabs, crs.
  1543. showRowCol     • if set, row and col are continuously
  1544.                  displayed in the title bar. 
  1545. sortColumn     • column to use for sort routine.
  1546. sortedIsDefault• if set, sorted is the default for 
  1547.                  function and section menus.
  1548. sortFuncsMenu  • Whether or not to sort the funcs menu.
  1549. suppressHeader • Suppress header on printed pages.
  1550. tagFile        • complete path-name of tag file
  1551. tearoffMenus   • toggles tear-off menus.
  1552. tile{Height,Left,Top,Width} • rectangle to tile windows
  1553.                  within.
  1554. tempMem        • Enable use of system temporary memory.
  1555. undoOn         • used to turn undo on and off. When undo
  1556.                  is turned off, all undo info is lost.
  1557.                  Useful when doing global replaces, etc.
  1558. wrapHigh       • Line length limit beyond which soft-wrapping occurs, if 
  1559.                  enabled.
  1560. wrapLow           •      ""            ""
  1561.  
  1562.  
  1563.           Spellchecking
  1564.  
  1565. Alpha has the capability to interact with the spell-check 'Excalibur', 
  1566. written by Robert Gottshall and Rick Zaccone.  The menu item 'Spellcheck 
  1567. Window' is always available in the "Utils" menu.  Selecting this item will 
  1568. start up Excalibur and send an OpenDoc event describing the current window.  
  1569. For version 1.4 and earlier, if Alpha has to launch Excalibur you will need 
  1570. to dismiss Excalibur's opening dialog by hitting the Cancel button.  
  1571. Subsequent selections of the menu item will switch right into Excalibur 
  1572. with the correct file displayed.  In future versions, this will become even 
  1573. more automatic.
  1574.  
  1575. Excalibur is free, but not in the public domain.  It can be obtained from 
  1576. all the usual Internet ftp sites, as well as cs.umd.edu under 
  1577. pub/faculty/keleher/Alpha.
  1578.  
  1579.  
  1580.           International Users
  1581.  
  1582. Everything should work. If it doesn't, please tell me.
  1583.  
  1584. There are two basic problems international users will notice.  The 
  1585. first is unavoidable, the second you can work around, and may be
  1586. fixed in a future version of Alpha.  The package 'internationalMenus'
  1587. will sort out most if not all of these difficulties for users of
  1588. any western keyboard.  However, if you do encounter any problems,
  1589. reading the following section will help to clarify things and should
  1590. help you to fix the problem.
  1591.  
  1592. The first problem is this: e.g. on a swiss keyboard, '/' is shift-7 
  1593. (which means you have to press shift to get '/'.  This means there is 
  1594. no difference between cmd-/ and shift-cmd-/ on such a keyboard.  In 
  1595. Alpha these are bound separately to 'zoom' and 'singlePage'.  You'll 
  1596. have to rebind them yourself to get different behaviour.  Something 
  1597. like this should work (save it in a file and put it in the packages 
  1598. directory, or just add the menu::replaceWith command to your prefs.tcl):
  1599.    
  1600.    # (auto-install)
  1601.    alpha::extension swissKeyboard 0.1 {
  1602.        menu::replaceWith winMenu [list "//<Szoom" "//<S<I<OsinglePage"] \
  1603.          items "<S//zoom" "<S<O<U/=singlePage"
  1604.    }
  1605.  
  1606. The second problem is that due to the differences between american and 
  1607. international keyboards, various keys may not be configured how Alpha 
  1608. expects.  This isn't a problem except that Alpha tries to map bindings 
  1609. between menus and 'bind' statements.  By default Alpha is configured 
  1610. to bind the '{' key to be electric in certain modes.  However the '{' 
  1611. key is shift-[ on american keyboards, so the binding must be made to 
  1612. that key.  On a swedish keyboard the binding is "bind '8' <so> 
  1613. bind::LeftBrace" -- so '{' is shift-option-8.  Alpha must be told how 
  1614. some such things work (in a future version, Alpha should be able to
  1615. ask the OS directly).  You can do this using the international 
  1616. preferences.
  1617.  
  1618. The best way is to define a line like this:
  1619.  
  1620.     set "keyboards(U.S.)" {
  1621.      {§1234567890-=[];'\`,./}
  1622.      {±!@#$%^&*()_+{}:"|~<>?}
  1623.      <U/[
  1624.      <U/]
  1625.     }
  1626.  
  1627. which contains four strings which Alpha uses to set these internal 
  1628. variables:
  1629.  
  1630.     keys::mapShiftBindFrom "`1234567890-=[]\;',./"
  1631.     keys::mapShiftBindTo   "~!@#$%^&*()_+{}|:"<>?"
  1632.     bind::leftBrace <U/[
  1633.     bind::rightBrace <U/]
  1634.  
  1635. which tell Alpha how to map using the 'shift' key.  Therefore on
  1636. an american keyboard, shift maps each item in the upper string into
  1637. the corresponding item in the lower string.  Set these strings up
  1638. and then any bindings you set will work ok.  A future version of
  1639. Alpha may remove the need for you to set these manually.
  1640.  
  1641. If you define an array entry keyboards(my-country), then you can just 
  1642. select that in the international prefs dialog, and Alpha will set the
  1643. flags correctly.  You can then send that keyboard array entry to the 
  1644. ALPHA-D mailing list (see Readme for details) for inclusion in a 
  1645. future version of Alpha.
  1646.  
  1647. If any other package defines bindings which depend upon these 
  1648. variables, you will need to restart Alpha after messing with the variables.
  1649. If a package wishes to be told when the keyboard changes, it can do 
  1650. that by registering with the 'removekeyboard' or 'keyboard' hooks like
  1651. this:
  1652.  
  1653.     # tell me when we switch to a "Swiss German" keyboard
  1654.     hook::register keyboard keys::swiss "Swiss German"
  1655.     # tell me when we disable a keyboard
  1656.     hook::register removekeyboard my_disable_proc
  1657.     # tell me when we enable a keyboard
  1658.     hook::register keyboard my_enable_proc
  1659.     
  1660. In this way a clever package could remove the need for restarting 
  1661. Alpha by unbinding and then rebinding all necessary items.
  1662.  
  1663.           Drag and Drop
  1664.  
  1665. Alpha supports drag and drop cut, copy, clear, and paste. To use this 
  1666. feature, select some text, then move the cursor over the selected text. 
  1667. The cursor should then turn into an open hand. Mouse down, and move the 
  1668. cursor to the place you wish to paste the text. When the mouse is 
  1669. released, the hilited text is moved to the new location.
  1670.  
  1671. Option-mouse does a "copy" instead. You can also drag selections between 
  1672. windows and to and from other applications, including the finder. Text 
  1673. can be deleted by dragging it to the trash can. 
  1674.  
  1675. You MUST have Apple's "Macintosh Drag And Drop" installed. Get a copy from Apple 
  1676. or via Alpha's web page.
  1677.  
  1678.  
  1679.  
  1680.           Status Bar
  1681.  
  1682. The stripe across the bottom of the screen is a floating window that 
  1683. displays status information, certain prompts (option-x, and see the func 
  1684. 'statusPrompt'), and the current row and column.
  1685.  
  1686. You can't make this window go away. However, both 'sizeWin' and 'moveWin' 
  1687. accept "StatusWin" as a window specification and will act on this window, 
  1688. so you can move the window offscreen if you really wish. The height
  1689. parameter to 'sizeWin' is ignored.
  1690.  
  1691. The status bar can be dragged if the flag 'lockStatus' is turned off.
  1692.  
  1693. Clicking over the row and column indicators allows you to jump to a 
  1694. particular line.
  1695.  
  1696. The left-most popup menu allows you to choose between simple wrapping when 
  1697. typing 
  1698.  
  1699. The left-most popup menu is the "File Flags" menu.  The next icon is the 
  1700. "Mode" popup menu, which shows the window's current mode and allows it to 
  1701. be changed.
  1702.  
  1703. Finally, if you turn horizontal scrollbars off (via the 'horScrollBar' 
  1704. flag in the "Config:Flags" menu, you haven't lost any real estate. 
  1705. Furthermore, when tiling windows vertically, you actually have *more* 
  1706. real estate. 
  1707.  
  1708.  
  1709.           Modes
  1710.  
  1711. Each window in Alpha is always in a single "mode", such as the "C++" mode, 
  1712. or the "TeX" mode.  A mode describes bindings and variable values 
  1713. particular to that mode.  The mode of the frontmost window is displayed and 
  1714. can be changed via the status bar.
  1715.  
  1716. Alpha sets modes for new windows based on file name suffixes.  For 
  1717. instance, "files.c" is started up in mode "C" because of the ".c" suffix.  
  1718. Below are some of the standard suffixes recognized by Alpha.  These 
  1719. suffixes can be changed via the 'Suffix Mapping' item in the "Config" menu. 
  1720. The default mode is "Text".
  1721.  
  1722.     .h, .c, .r                        C
  1723.     .cc, .cp, .cpp, .CPP, .C        C++
  1724.     .f .fcm .for .FOR                Fort
  1725.     .tcl                            Tcl
  1726.     .tex, .sty, .ltx, .dtx, .ins    TeX
  1727.     .pl                                Perl
  1728.     .html .HTML                        HTML
  1729.     
  1730. Bindings for a specific mode can be specified by passing the desired mode as 
  1731. the last argument to a 'bind' command (see "Key Bindings").
  1732.  
  1733. Alpha has two different types of immediately visible flags and variables: 
  1734. global and per-mode flags. These are listed in separate submenus under the 
  1735. Config menu.
  1736.  
  1737. "Mode" flags and variables are instantiated separately for each mode.  
  1738. These are inspected and set via the "Config:Current Mode" menu.  Changing 
  1739. these values affects every window in that mode, but doesn't affect windows 
  1740. in other modes.
  1741.  
  1742. The variables displayed in "Config:Current Mode" are all the variables that the 
  1743. current mode cares about.  The "Set Mode Menus…" item allows you to specify 
  1744. which of the extra menus should be present whenever the frontmost window is 
  1745. in that mode.  Select multiple menus by shift-clicking.
  1746.  
  1747. See here for more information on defining your own modes.
  1748.  
  1749. See here for information on removing existing modes (for disk space).
  1750.  
  1751.           File Comparison
  1752.  
  1753. Version 5.94 and above can create UNIX "diffs" of two text files. Among 
  1754. other things, diffs allow you to easily pinpoint what has changed between 
  1755. two different versions of the same file. 
  1756.  
  1757. Alpha's interface (under the "Utils" menu) allows you to compare either 
  1758. the two topmost windows, or two arbitrary files (later, Alpha will be 
  1759. able to compare entire directories). Alpha opens the two files in windows 
  1760. at the top of the screen with the diff file at the bottom. You can 
  1761. navigate between individual differences in the diff file by using the Up 
  1762. and Down arrows. Pressing either a carriage return or the Enter key 
  1763. displays the affected portions of the two files in the above windows.
  1764.  
  1765. I'm currently using a hack of QUED's GNU diff port.  My hack allows 
  1766. it to work as an AppleEvent server.  However, it handles most errors by 
  1767. quitting without responding, and handles only a single message before 
  1768. quitting. It also doesn't deal with directories. 
  1769.  
  1770. The interface is a 'dosc' script event containing the command-line 
  1771. arguments that would be used in running 'diff' from a UNIX shell (see 
  1772. here).  The result is the diff.  On the command line, file names containing 
  1773. spaces can be specified by delimiting the entire file name with double 
  1774. quotes.  The source for my version of the diff application (crude though it 
  1775. is), is available in pub/faculty/keleher/Alpha on cs.umd.edu.
  1776.  
  1777. Bugs: The files must have line Mac terminations.
  1778.  
  1779.  
  1780.  
  1781.           HyperText
  1782.  
  1783. Alpha's hypertext is both more and less powerful than systems that use 
  1784. markup languages such as HTML. It's more powerful because the action 
  1785. taken upon hitting a hypertext link is any arbitrary Tcl script rather 
  1786. than just navigation. It's less powerful because the generality doesn't 
  1787. allow a standard notion of going "back" or "forward". In any case, two 
  1788. points:
  1789.     1) The hypertext is only intended for Alpha documentation, and links 
  1790.     should not need to be created by anyone who isn't writing docs.
  1791.     
  1792.     2) 'pushMark' is called before any hypertext link is executed. This 
  1793.        allows you to return to the previous spot by "Pop Mark"ing (from the 
  1794.        Edit menu).
  1795.     
  1796. If you *must* create hypertext links, use the insertColorEscape command.
  1797.  
  1798.  
  1799.  
  1800.           Limitations
  1801.  
  1802. - Apple's listproc seems to have a total size limit of 32k characters. 
  1803.   This effectively limits tag searches to about 4000 function names.
  1804.  
  1805.  
  1806.           Preferences
  1807.  
  1808. Alpha saves settings between sessions by writing them to files in an 
  1809. "Alpha" sub-folder of the system preferences folder.  Additionally, Alpha 
  1810. will source a file called "prefs.tcl" from this sub-folder if it exists.  
  1811. You can view or remove the settings currently being saved there at any time 
  1812. via the "View/Remove Saved Settings…" from the Edit menu. You can edit 
  1813. the prefs.tcl file via the "Edit prefs.tcl" item. 
  1814.  
  1815. Never add manually add text to the defs.tcl or arrdefs.tcl files in the 
  1816. preferences folder. These files are automatically generated and read by 
  1817. the addDef etc. functions. If you need to save variable definition from 
  1818. Tcl code, addDef etc. is your friend. 
  1819.  
  1820. If you want to have arbitary code executed on startup, you can manually 
  1821. place this in the prefs.tcl file.
  1822.  
  1823. Holding down the shift key at startup causes Alpha to skip all preferences 
  1824. files.
  1825.  
  1826.  
  1827.           Changing Alpha's Behavior
  1828.  
  1829. Alpha's behavior can be modified in five primary ways.  The first is by 
  1830. changing flag and variable values.  Mode-independent flags and variables 
  1831. are under the "Config:Flags" menu.  Mode-dependent flags and variables are 
  1832. in "Config:Current Mode".  Values of all of these flags and variables are 
  1833. saved when Alpha exits.
  1834.  
  1835. The second method is to write an 'extension'.  See the 'Extending 
  1836. Alpha' help file for details.  Extensions are conveniently packaged 
  1837. pieces of Tcl code which have a startup section and a main section and 
  1838. are labelled via a name and version number.  They may be conveniently 
  1839. turned on or off using the Packages menu, and can be distributed to 
  1840. other Alpha users without the requirements for complex installation 
  1841. instructions.
  1842.  
  1843. The third method is to add bindings or Tcl procs to 'prefs.tcl', Alpha's 
  1844. preference file.  This file is accessible from the "Config" menu as well.  
  1845. 'prefs.tcl' is sourced at the end of Alpha's startup procedure.
  1846.  
  1847. The fourth way to modify Alpha's behavior is to create mode-specific prefs 
  1848. files. These files are created through the Config menu. Mode-specific prefs 
  1849. are loaded after the corresponding mode has been entered for the first 
  1850. time.
  1851.  
  1852. The final recomended way to modify Alpha is to create files that are 
  1853. sourced after corresponding files in Alpha's :Tcl:SystemCode directory. See 
  1854. here for more details.
  1855.  
  1856. Finally, you could just hack the files in SystemCode directly. However, 
  1857. you should definitely know what you are doing if you resort to this method, 
  1858. and it's definitely *not* portable from one version of Alpha to the next.
  1859.  
  1860.  
  1861.  
  1862.           HTML
  1863.  
  1864. See here.
  1865.  
  1866.  
  1867.  
  1868.           Internet Config
  1869.  
  1870. "Internet Config" is a freeware utility that holds system-wide preferences, 
  1871. especially preferences that might be accessed by more than one 
  1872. application.  For example, Internet Config stores pointers to helpers for 
  1873. web services, ftp, etc.  
  1874.  
  1875. Alpha supports "Internet Config" in the following ways: (i) 
  1876. command-clicking on highlighted text causes the text to be sent to Internet 
  1877. Config to be launched, (ii) the Internet Config menu allows either Internet 
  1878. Config itself, or several of it's internet helpers, to be started, and iii) 
  1879. Alpha can query internet config for path names in the "Config:App Paths" 
  1880. dialog. 
  1881.  
  1882. Click here for more information.  Once you have installed it and set up 
  1883. your ftp helper app through Internet Config, you can retrieve the entire 
  1884. package by clicking here.
  1885.  
  1886. The "URLs" submenu allows you to store a few commonly used URLs and to 
  1887. launch them, regardless of what helper they are directed to.
  1888.  
  1889. For instance, my menu includes 
  1890.  
  1891. New York Times       "http://www.nytimes.com/info/contents/contents.html"
  1892. Latest TCL Source    "ftp://ftp.aud.alcatel.com/tcl/ftp.smli.com/mac/"
  1893. Down                 "ftp://keleher:passwd@cs.umd.edu/down/"
  1894.  
  1895. where 'passwd' is replaced by my real password (and is understood by 
  1896. Anarchy, among others).
  1897.  
  1898. The function icURL can be to send URLs to internet config. For instance, I 
  1899. have the following proc defined in my prefs that allows me to access any 
  1900. arbtrary directy of my unix box at school merely by typing "ftp <dir>":
  1901.  
  1902.     proc ftp {{arg ""}} {
  1903.         icURL "ftp://keleher:passwd@cs.umd.edu/$arg"
  1904.     }
  1905.  
  1906. The 'Finger' item sends a fetchurl event to Peter Lewis's "Finger" program. 
  1907.  
  1908.  
  1909.           Calculator
  1910.  
  1911. Alpha now has its own calculator :-), entirely implemented in Tcl.  This is 
  1912. just a quick-and-dirty RPN stack calculator, works on both signed and
  1913. unsigned decimals, hex integers, and floating point.  I put it together for 
  1914. my own use, not yours, but feel free to use it as long as you don't complain 
  1915. about what it doesn't do. Improvements, of course, are welcome.
  1916.  
  1917. Operations:                                                             
  1918.     +,-,*,/,|,&,%    Top    of stack is    'y', next is 'x'. Does x OP    y.     
  1919.     ~                bitwise NOT                                         
  1920.     ^                x eor y                                             
  1921.     <                x << y                                             
  1922.     >                x >> y                                             
  1923.     c                change y's sign                                     
  1924.     q                dup    y                                             
  1925.     i                swap x and y                                     
  1926.     m                switch signed/unsigned/hex modes                         
  1927.     x                show current mode
  1928.     h or ?            help
  1929.     <delete>        pop    stack                                         
  1930.     <space>            enter number                                     
  1931.  
  1932. Invoke from the File menu, holding down the shift key.
  1933.  
  1934.  
  1935.  
  1936.           Templates
  1937.  
  1938. Temporary marks can also be used to with language construct templates.  
  1939. The file "templates.tcl" contains basic template support, and the 
  1940. Vince's Additions package (an extension you may download) provides a 
  1941. more feature rich version.  Templates are pieces of code/text with
  1942. predefined 'template-stops' at which the user will want to enter 
  1943. information.  For instance, in C mode, you can save a lot of typing by 
  1944. using 'for' templates, which insert 'for (•;•;•) { • }'.  By default 
  1945. 'tab' and 'shift-tab' are used to move forwards and backwards between 
  1946. the bullets (which are the template-stops).
  1947.  
  1948. As of Alpha 7.0, the old 'electricAlias' package no longer functions 
  1949. correctly.  It would be relatively easy for a user to fix it up to
  1950. work again.  Similar functionality is provided via Alpha's new 
  1951. built-in templates and extended by Vince's Additions.
  1952.  
  1953.           Ftp Browser
  1954.  
  1955. The 'FTP' menu allows quick access to files on a remote ftp server, useful 
  1956. for those that work on both unix and mac systems. You should have Anarchy 
  1957. installed as your ftp server, although Fetch might work as well. Popup menu 
  1958. in title of any "remote" window allows repeated access to those 
  1959. directories.
  1960.  
  1961. More docs later, once someone sends them to me. Please volunteer....
  1962.  
  1963.  
  1964.  
  1965.  
  1966.           Deconstructing Alpha
  1967.  
  1968. Use the 'Packages->Uninstall package…' menu item to remove modes menus 
  1969. or extensions you don't use.  This *permanently* removes tcl and help 
  1970. files pertaining to the offending modes and menus.  Only a 
  1971. re-installation can get them back.
  1972.  
  1973.  
  1974.  
  1975. Remember, Alpha's official home site is:
  1976.  
  1977.         http://www.cs.umd.edu/~keleher/alpha.html
  1978.  
  1979.                 or
  1980.  
  1981.         ftp://www.cs.umd.edu/pub/faculty/keleher/Alpha/
  1982.  
  1983.